.\" man file clone(1)
.\"
.\" Created by Dr. Rolf Jansen on 2013-01-13.
.\" Copyright (c) 2013-2015. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without modification,
.\" are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
.\" OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
.\" THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd 2015-05-01
.Dt clone 1 URM                        \" Program name and manual section number
.Os FreeBSD, Darwin
.Sh NAME                               \" Section Header - required - don't modify 
.Nm clone
.Nd A file tree cloning tool
.Sh SYNOPSIS                           \" Section Header - required - don't modify
.Nm
.Op Fl c Ar roff|woff|rwoff            \" [-c roff|woff|rwoff]
.Op Fl d Ns | Ns Fl i Ns | Ns Fl s     \" [-d|-i|-s]
.Op Fl v Ar level                      \" [-v level]
.Op Fl x Ar exclude-list               \" [-x exclude-list]
.Op Fl X Ar excl-list-file             \" [-X excl-list-file]
.Op Fl y                               \" [-y]
.Op Fl h Ns | Ns Fl \&? Ns | Ns Sy \&? \" [-h|-?|?]
.Ar source/                            \" required argument
.Ar destination/                       \" required argument
.Sh DESCRIPTION                        \" Section Header - required - don't modify
.Nm
is a file tree cloning tool which runs 3 threads - a scheduler (main), a reader, and a writer thread. Reading and writing occurs in parallel. While this is most beneficial for copying data from one physical disk to another,
.Nm
is also very well suited for cloning a file tree to any place on the same disk.
.Pp
Cloning includes the whole directory hierarchy, i.e. sub-directories, files, hard links, symbolic links, attributes (modes, flags, times), extended attributes and access control lists.
.Pp
.Nm
is useful for cloning (thus backing-up) live file systems, and it can also be used in incremental and synchronization mode.
.Pp
.Nm
works on FreeBSD and Mac OS X.
.Pp
.Nm
is very fast, for example, cloning a whole UFS2 file hierarchy on FreeBSD 9.1 of in total 2.3 TBytes of data from one hard disk to another took 7.5 h, so the average transfer rate for all kind of files (very small up to very big ones) was about 89 MByte/s.
.Pp
\fBOptional flags:\fP
.Bl -tag -width -indent
.It Fl c Ar roff | woff | rwoff
Selectively turn off the file system cache for reading or writing or for reading and writing -- the caches are on by default.
.It The options -d, -i, -s are mutually exclusive:
.It Fl d
Delete the contents of the destination before cloning, but do not remove the destination directory or mount point itself. Stop on error. Deletion requires user confirmation, unless it is confirmed inherently by the \fB-y\fP flag. Be careful, deletion cannot be undone! NOTE: It may take its time to empty hugh file trees, and it may be faster to use \fBnewfs(8)\fP for initializing big volumes.
.It Fl i
Incrementally add new content to or change content in the destination, but do not touch content in destination that does not exist in source.
.It Fl v
Verbosity level (default = 1):
.br
0 - no output
.br
1 - show directory action: + for add, - for delete, = for keep
.br
2 - indicate cloned files by '.'
.br
3 - display the path names of cloned file system items
.It Fl s
Completely synchronize destination with source.
.It Fl x Ar exclude-list
Colon separated list of entity names or full path names to be excluded from cloning. Use full path names to single out exactly one item. Use entity names for all existing entities having that name being excluded.
.br
For example: -x ".snap:/.sujournal:.DS_Store:/fullpath/to a/volatile cache"
.It Fl X Ar excl-list-file
File containing a list of entity names or full path names to be excluded -- one item per line.
.It Fl y
Automatically answer with y(es) to y|n confirmation prompts.
.It Fl h | Fl \&? | Sy \&?
Show the usage instructions.
.El
.Pp
\fBRequired arguments:\fP
.Bl -tag -width -indent
.It Ar source/
Path to the source directory or mount point to be cloned. The final '/' may be omitted.
.It Ar destination/
Path to the destination directory or mount point. If the destination does not exist, then it will be created. The final '/' may be omitted. 
.El
.Pp
.Sh EXAMPLES
.Bl -tag -width -indent
.It Initial cloning of the root volume \fI/\fP to a volume mounted on \fI/mnt\fP:
clone / /mnt
.It Same as above, but empty \fI/mnt\fP before cloning:
clone -d / /mnt
.It Incrementally update the clone with respect to the master:
clone -i / /mnt
.It Keep the clone exactly synchronized to the master:
clone -s / /mnt
.It Create a non-versioned clone of a versioned source tree:
clone -x .svn /path/to/my/project /path/to/non-versioned/project
.It Clone a directory to a share and strip file system specific meta data:
clone -x ".DS_Store:.AppleDouble:.AppleDesktop:.appdisk" /path/to/afpvol /path/to/the/share
.El
.Sh SEE ALSO
.Xr cp 1 , 
.Xr ditto 1 ,
.Xr rsync 1 ,
.Xr dd 1 ,
.Xr newfs 8 ,
.Xr dump 8 ,
.Xr restore 8 ,
.Xr asr 8
.Sh AUTHOR
.An Dr. Rolf Jansen. Copyright (c) 2013-2015. All rights reserved.
.Sh IMPORTANT NOTE
Inproper use of
.Nm
may delete or overwrite data. Take special care with the -d and the -s option. Also always be sure, that the last command line argument designates a path to a file tree which really is under disposition.
.Pp
In NO event shall the author and/or copyright owner be liable for ANY damages resulting from ANY use of this software. Use
.Nm
at your own risk!
.Sh BUGS
.Nm
has been carefully developed and tested. Anyway,
.Nm
is provided without any expressed or implied warrantee on being 100 % bug free.
